<h1><a id="Multilanguage">Multilanguage</a></h1>
<p>KwaMoja can be translated to any language so that the entire web-interface is displayed in the language of any user. The system can display different languages for different users - all at the same time - depending on the setting of the language in the individual users' settings.</p>
<p>The recommended procedure to create a translation is as follows:<br></p>
<ol>
	<li><a href="http://lists.sourceforge.net/lists/listinfo/web-erp-translation">Join the mailing list here</a><br>
		Let the list know you're wanting to help with a translation - someone may already be working on it.
	</li>
	<li>Obtain the latest messages.po file and enter the translations using your favourite editor (or poedit). The latest messages.po file is included with the latest archive:<br>
		www_root/KwaMoja/locale/en_GB/LC_MESSAGES/message.po&lt; br /&gt; Edit the file provided entering the translations for the strings labelled msgid in the string labelled msgstr. Watch for html strings embedded inside the strings the html will also be required in the translated string. Also be sure to ensure that each translated string is enclosed in speech marks ("). Please also complete the translation file header information - with your details so that you are accorded proper recognition for your contribution.
	</li>
</ol>
<p>It is especially important to ensure that the string "ISO-8859-1" (at the time of writing around line 19400 in the messages.po file) is translated to be the character set that you wish your translation to use. KwaMoja uses the translated string here to send appropriate html headers so your browser knows how to interpret the characters sent.</p>
<p>It is worthwhile investigating the poedit package as this has some time saving features for creating gettext translation files.</p>
<p>Return the file containing your translations to submissions@kwamoja.com</p>
<p>An archive of the new language directory and instructions will be put up on sourceforge so everyone can access your translation.</p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>Technical Overview</h2>
<h3>How is it Done</h3>
<p>KwaMoja uses the GNU gettext package for language translations. For the gettext library to be used - which must be installed on your webserver, PHP must be compiled with gettext functions. However, since version 3.01 thanks to Briain Gomez and the authors of PHP-GETTEXT Danilo Segan and Nico Kaiser their php class to enable the translations to work (albeit more slowly than the gettext library functions) is bundled with KwaMoja so translations will still work even though gettext is not installed.</p>
<p>The gettext translation files are held in the locale directory, under this directory there are sub-directories for each locale, a five character code representing the language to be used. eg en for English an underscore and then another two character code in capitals for the local version of the language eg US for USA - so the full locale code becomes en_US. For english of the Great British variety - the full locale code is then en_GB - this is the default language that KwaMoja is written in. The locale for this code needs to be installed on the web-server - all locales installed can be inspected using the command line #locale -a on a linux web server.</p>
<p>New directories will need to be made up if a translator wishes to have a local version for their language. Under the locale directory the five character locale abbreviation code directory there is a further sub-directory called LC_MESSAGES - this is where the translation files exist. There are two files in each of these directories:</p>
<p></p>
<ol>
	<li>messages.po this file contains all the strings to be translated. This is the only file of concern for translators</li>
	<li>messages.mo this is a binary machine searchable translation file used by gettext. The .mo file is automatically produced by a gettext utility (msgfmt.exe or msgfmt in *nix) using the messages.po file (the syntax from a command window is msgfmt.exe messages.po). The main effort is required to get the .po file translated - the .mo file is easily and happily created by the KwaMoja project admin if required.</li>
</ol>
<p>Any text editor can be used to edit the .po file (GNU Emacs contains specific functionality for editing .po files there is a special PO-Mode) - there is also a utility called poedit which is often recommended by translators.</p>
<p></p>
<h3>Understanding the messages.po File</h3>
<p>The translation is performed by tranlating the strings in the messages.po file into the other language. It is important to work on the most recent messages.po file from the locale/en_GB/LC_MESSAGES/ deirectory in the CVS. This can be downloaded from http://web-erp.cvs.sourceforge.net/viewvc/*checkout*/web-erp/KwaMoja/locale/en_GB/LC_MESSAGES/messages.po</p>
<p>The messages.po is made up of sections</p>
<p>eg. for a French translation file</p>
<p>#: AccountGroups.php:8 index.php:890<br>
	msgid "An example string in English that needs to be translated"<br>
	msgstr="Une corde d'exemple dans le ce anglais doit &#234;tre traduite "
</p>
<p>the line #: AccountGroups.php:8 index.php:890<br>
	means that the string following is used in the AccountGroups.php script on line 8 and the index.php script on line 890. It could be useful to understand the context of where the script is used. Strings that are used several times throughout the application only need to be translated once. In some cases the #: line showing where the string is used can be quite an extensive list of scripts.<br>
</p>
<p>msgid "An example string in English that needs to be translated"<br>
	this line is the english string which is to be substituted by the text in msgstr. If the value of msgstr is empty - "". gettext will return the english string.
</p>
<p>The effort of the translation is to edit the messages.po file and enter the language translation within the inverted commas of the msgstr.</p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>The .po File Header</h2>
<h4>The .po file starts with some initial comments which should also be completed</h4>
<p>"SOME DESCRIPTIVE TITLE", - should be replaced with KwaMoja - LANGUAGE Translation File - where LANGUAGE is the language being translated into<br>
	# FIRST AUTHOR , YEAR. - should be your name and email address - with the year of the work being done
</p>
<h4>Project-Id-Version</h4>
<p>Should be KwaMoja - version number</p>
<h4>PO-Revision-Date</h4>
<p>This is the date of your last entries in the file</p>
<h4>Last-Translator</h4>
<p>This is your name and email address for users of this language to contact should some translations be unclear</p>
<h4>Content-Type</h4>
<p>Replace `CHARSET' with the character encoding used for your language, in your locale, or UTF-8.</p>
<p>In the GNU system, the following encodings are frequently used for the corresponding languages:</p>
<ul>
	<li>ISO-8859-1 for Afrikaans, Albanian, Basque, Catalan, Dutch, English, Estonian, Faroese, Finnish, French, Galician, German, Greenlandic, Icelandic, Indonesian, Irish, Italian, Malay, Norwegian, Portuguese, Spanish, Swedish,</li>
	<li>SO-8859-2 for Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian,</li>
	<li>ISO-8859-3 for Maltese,</li>
	<li>ISO-8859-5 for Macedonian, Serbian,</li>
	<li>ISO-8859-6 for Arabic,&lt;&lt;/li&gt;</li>
	<li>ISO-8859-7 for Greek,</li>
	<li>ISO-8859-8 for Hebrew,</li>
	<li>ISO-8859-9 for Turkish,</li>
	<li>ISO-8859-13 for Latvian, Lithuanian,</li>
	<li>ISO-8859-15 for Basque, Catalan, Dutch, English, Finnish, French, Galician, German, Irish, Italian, Portuguese, Spanish, Swedish,</li>
	<li>KOI8-R for Russian,</li>
	<li>KOI8-U for Ukrainian,</li>
	<li>CP1251 for Bulgarian, Byelorussian,</li>
	<li>GB2312, GBK, GB18030 for simplified writing of Chinese,</li>
	<li>BIG5, BIG5-HKSCS for traditional writing of Chinese,</li>
	<li>EUC-JP for Japanese,</li>
	<li>EUC-KR for Korean,</li>
	<li>TIS-620 for Thai,</li>
	<li>UTF-8 for any language, including those listed above.</li>
</ul>
<p>Since there are such a lot of potential characters in utf-8, the size of font files necessary to be embedded in pdf files makes the resulting pdf file too big to be sent over dial up connections and is therefore to be avoided in favour of the more specific character sets above.</p>
<p>The character encoding name can be written in either upper or lower case. Usually upper case is preferred.</p>
<h4>Content-Transfer-Encoding</h4>
<p>Set this to 8bit</p>
<h4>Administration</h4>
<p>Once this exercise has been completed the file must be returned to the project administrator: submissions@kwamoja.com for the .mo file to be created. The new directory will be returned in a zip file for extraction from the KwaMoja directory. The language will then be added to the KwaMoja system for the benefit of other users as well.</p>
<p>Upon logging into the system each time the system sets the language used by looking up the user information to see what language they have set, The user can change which language is set by clicking on their user name at the top left which brings up User Settings. Changing the language setting will activate the new language right away upon saving the change. Only languages for which there is a directory under the locale directory are allowed to be selected by users.</p>
<h4>Other Resources</h4>
<p><a href="http://www.gnu.org/software/gettext/manual/html_chapter/gettext_toc.html#SEC_Contents">The GNU gettext manual</a></p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>Translation Utilities</h2>
<p>KwaMoja comes bundled with some on-line tools for adminstering translations - there are some issues with maintaining translations using these facilities - in particular certain characters cause problems for the scripts and character encodings can be lost. It is therefore not recommended to use these except for adhoc maintenance where a backup of the most recent messages.po is held elsewhere.</p>
<p>The following explains how to use the language translation utilities provided with KwaMoja for the purpose of adding languages and maintaining their translations.</p>
<p>In general before using the utilities you need to click on your user name at the top left in order to access user preferences. Select the language to translate and click on Modify. The language utilities all use the currently selected user language. If the language you wish to use is not there then a new translation can be initiated with the 'Add a New Language' utility - see below. By default a new install of KwaMoja will only have the english - en_GB available. The most recent submitted language packs are available from the <a href='http://sourceforge.net/project/showfiles.php?group_id=70949'>sourceforge KwaMoja page</a></p>
<p>Translations are maintained from the utilities menu - this does not have its own link on the main menu since it is an area that only the system administrator should be able to access. Unauthorised modification of translation files is therefore discouraged. The utlities menu is Z_index.php - so you can modify the URL on the main menu by prefixing it with Z_ - this brings up the utilities menu - only if you have system administrator permissions on your user account. The link to 'Maintain Language Files' is where the translations are managed.</p>
<p>There are four translation utilities availble:</p>
<ul>
	<li>Rebuild the System Default Language File</li>
	<li>Add a New Language to the System</li>
	<li>Edit a Language File Header</li>
	<li>Edit a Language File Module</li>
</ul>
<p>Note that the discussion about what the system does is intended for those handling the system and its files. It is not necessary to understand if you are only dealing with translation.</p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>Rebuild the System Default Language File</h2>
<p>The system has one default language file. When a new language is created it makes a copy of this file for itself that can be edited for that language. The rebuilding this system default language file consists of it looking through every system code file (script) in order to create a new system default language file. In this way, any modifications or additions to strings will be contained within the newly created file. This can be done before creating a new language in order to start with the very latest strings.</p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>Add a New Language to the System</h2>
<p>Use this utility to create a new language. It is important to recognise that only languages that have appropriate locale files on your web-server can be added. The language identifier must match with the language files on the web-server. Enter the language in the form xx_XX where the first two characters are the lower case standard code for the language such as en for English and the last two are the upper case standard code for the country such as US for United States. This example would be en_US. The underscore must separate the language and country for a total of 5 characters. The Proceed button must be clicked after entering the language in order for it to be created. The system then creates a new language directory under the locale directory and an LC_MESSAGES directory under this new language directory. Then, in this new locale/xx_XX/LC_MESSAGES directory it copies accross the Default Language file (messages.po). Initially there are no translations in the new messages.po file.</p>
<p>Once the new language has been created, to use the language translation utlities to maintain the new translation you must change to the new language. To change language, the user name shown at the top left of all KwaMoja screens is clicked on and the drop down box should now show the new language created above. Select the new language to enable you to operate with the translation utilities.</p>
<p>It is not necessary to know about the structure of the language file if using the translation tools provided. The details below are presented for infomation purposes only. The language file - messages.po consists of:</p>
<ul>
	<li>A header, containing details of the translator and of critical importance the character set required to represent the letters in the language.</li>
	<li>Message identification strings that start with msgid then the english string that is to be translated surrounded by quotation marks. The scripts in which the string occurrs are noted above each msgid statement</li>
	<li>Message strings such as msgstr "" - in a new messages.po these are all "". The job of translating requires that the msgstr be entered for the language to represent the text in the msgid string.</li>
</ul>
<h2>Edit a Language File Header</h2>
<p>The language file header can be modified using this utility. One important reason for modifying the header is to modify the charset to what is suitable for the locale. For en, the charset is usually set to 8829-1 or something like that. After editing the various areas of the header make sure to click on Enter Information at the bottom in order to save the changes.</p>
<div class="floatright">
	<a class="minitext" href="#top">⬆ Top</a>
</div>
<h2>Edit a Language File Module</h2>
<p>The majority of the translation work is done with this utility. First select the language you wish to edit and then there is a choice of modules. For a complete translation of the entire system all of the modules must be completed. Many prefer to do index.php and includes/header.inc first in order for the main menu to be in their language. From that point, the most important modules can be done first or all can be done alphabetically. Some memorable system should be used though in order to remember which modules still need translating in subsequent sessions.</p>
<p>Once the language and module have been selected then click on Proceed. A handy interface comes up with all of the strings listed that are within that module and beside them an area to enter your translation of that string. On the right is a list of the line number where the string occurs in the code within the module. After entering some translations click on Enter Information in order to save all changes.</p>
<p>If there has been some development work on your version of KwaMoja it is possible to merge any new strings that have been created by the developers with the existing language file and create a new messages.po that contain all the strings required by the system. If some messages still come up in English but they don't appear when editing the module for that screen then you know you must Merge the existing messages.po with any new messages. To ensure all strings are extracted by the gettext utility it is important to ensure that the "Rebuild the System Default Language File" is run first. Then from the "Edit a Language File Module" screen click on the "Refresh Messages With Latest Strings" - this merges the newly creates master messages.po file created by the Rebuild with your existing translations.</p>